DOC: Correct quiver and streamline figure factory return types - #5823

Summary

Related to #5396.

The figure-factory documentation currently describes create_quiver() and create_streamline() as returning dictionaries, even though both functions return plotly.graph_objects.Figure instances.

• Replace the misleading dict return-type descriptions with clear NumPy-style Returns sections.

• Add focused tests that verify both the return-type documentation and the actual Figure objects.

• Leave runtime plotting behavior and public API unchanged.

Verification

Executed on Windows / Python 3.11 against fork commit 1cd3b20:

python -m pytest -q tests/test_optional/test_figure_factory/test_return_type_docs.py --disable-warnings --maxfail=1

2 passed, 7 warnings

python -m ruff check plotly/figure_factory/_quiver.py plotly/figure_factory/_streamline.py tests/test_optional/test_figure_factory/test_return_type_docs.py

All checks passed!

python -m ruff format --check plotly/figure_factory/_quiver.py plotly/figure_factory/_streamline.py tests/test_optional/test_figure_factory/test_return_type_docs.py

3 files already formatted

git diff --check

(no issues)

This is targeted verification, not a claim that the full upstream CI suite has passed. No changelog entry is needed for this documentation-only change.

AI assistance disclosure

OpenAI ChatGPT assisted with selecting the narrowly scoped documentation issue, drafting the change, and preparing its regression tests. The contributor remains responsible for the content and addressing maintainer feedback.

Additional existing regression tests (16 October 2026)

On the same PR commit 1cd3b20, independently ran Plotly's existing quiver and streamline tests:

python -m pytest -q tests/test_optional/test_figure_factory/test_figure_factory.py -k 'TestQuiver or TestStreamline' --disable-warnings --maxfail=1

8 passed, 14 deselected, 7 warnings

Combined with the new documentation assertions: 10 targeted test passes across two runs, with no failures. This is not a full upstream suite run. The first-contributor GitHub Actions workflows remain in action_required until an upstream maintainer permits them.

Extended figure-factory module verification (16 October 2026)

After installing the previously missing optional scikit-image dependency into an isolated Python 3.11 environment, re-ran both complete relevant test files on exact PR commit 1cd3b20:

python -m pytest -q tests/test_optional/test_figure_factory/test_figure_factory.py tests/test_optional/test_figure_factory/test_return_type_docs.py --disable-warnings --maxfail=1
24 passed, 7 warnings in 65.38s (0:01:05)
exit code: 0

The 24 passes include the prior 10 targeted assertions; counts must not be added together. This does not establish a full Plotly test suite pass or maintainer-enabled GitHub Actions CI. The seven warnings were suppressed in summary, not triaged individually.